

<!DOCTYPE html>
<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
<head>
  <meta charset="utf-8">
  
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  
  <title>9. Modifying &amp; extending LIGGGHTS(R)-PUBLIC &mdash; LIGGGHTS v3.X documentation</title>
  

  
  
  
  

  

  
  
    

  

  
  
    <link rel="stylesheet" href="_static/css/theme.css" type="text/css" />
  

  

  
    <link rel="top" title="LIGGGHTS v3.X documentation" href="index.html"/>
        <link rel="next" title="10. Python interface to LIGGGHTS(R)-PUBLIC" href="Section_python.html"/>
        <link rel="prev" title="8. How-to discussions" href="Section_howto.html"/> 

  
  <script src="_static/js/modernizr.min.js"></script>

</head>

<body class="wy-body-for-nav" role="document">

   
  <div class="wy-grid-for-nav">

    
    <nav data-toggle="wy-nav-shift" class="wy-nav-side">
      <div class="wy-side-scroll">
        <div class="wy-side-nav-search">
          

          
            <a href="Manual.html" class="icon icon-home"> LIGGGHTS
          

          
          </a>

          
            
            
              <div class="version">
                v3.X
              </div>
            
          

          
<div role="search">
  <form id="rtd-search-form" class="wy-form" action="search.html" method="get">
    <input type="text" name="q" placeholder="Search docs" />
    <input type="hidden" name="check_keywords" value="yes" />
    <input type="hidden" name="area" value="default" />
  </form>
</div>

          
        </div>

        <div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
          
            
            
              
            
            
              <ul class="current">
<li class="toctree-l1"><a class="reference internal" href="Section_intro.html">1. Introduction</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_start.html">2. Getting Started</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_input_script.html">3. Input Script</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_commands.html">4. Commands</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_gran_models.html">5. Contact models</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_mesh_modules.html">6. Mesh modules</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_packages.html">7. Packages</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_howto.html">8. How-to discussions</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="">9. Modifying &amp; extending LIGGGHTS(R)-PUBLIC</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#atom-styles">9.1. Atom styles</a></li>
<li class="toctree-l2"><a class="reference internal" href="#compute-styles">9.2. Compute styles</a></li>
<li class="toctree-l2"><a class="reference internal" href="#dump-styles">9.3. Dump styles</a></li>
<li class="toctree-l2"><a class="reference internal" href="#dump-custom-output-options">9.4. Dump custom output options</a></li>
<li class="toctree-l2"><a class="reference internal" href="#fix-styles">9.5. Fix styles</a></li>
<li class="toctree-l2"><a class="reference internal" href="#input-script-commands">9.6. Input script commands</a></li>
<li class="toctree-l2"><a class="reference internal" href="#pairwise-potentials">9.7. Pairwise potentials</a></li>
<li class="toctree-l2"><a class="reference internal" href="#region-styles">9.8. Region styles</a></li>
<li class="toctree-l2"><a class="reference internal" href="#thermodynamic-output-options">9.9. Thermodynamic output options</a></li>
<li class="toctree-l2"><a class="reference internal" href="#variable-options">9.10. Variable options</a></li>
<li class="toctree-l2"><a class="reference internal" href="#submitting-new-features-for-inclusion-in-liggghts-r-public">9.11. Submitting new features for inclusion in LIGGGHTS(R)-PUBLIC</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="Section_python.html">10. Python interface to LIGGGHTS(R)-PUBLIC</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_errors.html">11. Errors</a></li>
</ul>

            
          
        </div>
      </div>
    </nav>

    <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">

      
      <nav class="wy-nav-top" role="navigation" aria-label="top navigation">
        
          <i data-toggle="wy-nav-top" class="fa fa-bars"></i>
          <a href="Manual.html">LIGGGHTS</a>
        
      </nav>


      
      <div class="wy-nav-content">
        <div class="rst-content">
          















<div role="navigation" aria-label="breadcrumbs navigation">

  <ul class="wy-breadcrumbs">
    
      <li><a href="Manual.html">Docs</a> &raquo;</li>
        
      <li>9. Modifying &amp; extending LIGGGHTS(R)-PUBLIC</li>
    
    
      <li class="wy-breadcrumbs-aside">
        
            
            <a href="_sources/Section_modify.txt" rel="nofollow"> View page source</a>
          
          <a href="http://www.cfdem.com"> Website</a>
          
            <a href="Section_commands.html#comm" rel="nofollow"> Commands</a>
            
          
        
      </li>
    
  </ul>

  
  <hr/>
  
    <div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
      
        <a href="Section_python.html" class="btn btn-neutral float-right" title="10. Python interface to LIGGGHTS(R)-PUBLIC" accesskey="n">Next <span class="fa fa-arrow-circle-right"></span></a>
      
      
        <a href="Section_howto.html" class="btn btn-neutral" title="8. How-to discussions" accesskey="p"><span class="fa fa-arrow-circle-left"></span> Previous</a>
      
    </div>
  
</div>
          <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
           <div itemprop="articleBody">
            
  <div class="section" id="modifying-extending-liggghts-r-public">
<h1>9. Modifying &amp; extending LIGGGHTS(R)-PUBLIC<a class="headerlink" href="#modifying-extending-liggghts-r-public" title="Permalink to this headline">¶</a></h1>
<p>This section describes how to customize LIGGGHTS(R)-PUBLIC by modifying
and extending its source code.</p>
<div class="contents local topic" id="contents">
<ul class="simple">
<li><a class="reference internal" href="#atom-styles" id="id9">Atom styles</a></li>
<li><a class="reference internal" href="#compute-styles" id="id10">Compute styles</a></li>
<li><a class="reference internal" href="#dump-styles" id="id11">Dump styles</a></li>
<li><a class="reference internal" href="#dump-custom-output-options" id="id12">Dump custom output options</a></li>
<li><a class="reference internal" href="#fix-styles" id="id13">Fix styles</a></li>
<li><a class="reference internal" href="#input-script-commands" id="id14">Input script commands</a></li>
<li><a class="reference internal" href="#pairwise-potentials" id="id15">Pairwise potentials</a></li>
<li><a class="reference internal" href="#region-styles" id="id16">Region styles</a></li>
<li><a class="reference internal" href="#thermodynamic-output-options" id="id17">Thermodynamic output options</a></li>
<li><a class="reference internal" href="#variable-options" id="id18">Variable options</a></li>
<li><a class="reference internal" href="#submitting-new-features-for-inclusion-in-liggghts-r-public" id="id19">Submitting new features for inclusion in LIGGGHTS(R)-PUBLIC</a></li>
</ul>
</div>
<p>LIGGGHTS(R)-PUBLIC is designed in a modular fashion so as to be easy to modify and
extend with new functionality.  In fact, about 75% of its source code
is files added in this fashion.</p>
<p>In this section, changes and additions users can make are listed along
with minimal instructions.  If you add a new feature to LIGGGHTS(R)-PUBLIC and
think it will be of interest to general users, we encourage you to
submit it to the developers for inclusion in the released version of
LIGGGHTS(R)-PUBLIC.  Information about how to do this is provided
<span class="xref std std-ref">below</span>.</p>
<p>The best way to add a new feature is to find a similar feature in
LIGGGHTS(R)-PUBLIC and look at the corresponding source and header files to figure
out what it does.  You will need some knowledge of C++ to be able to
understand the hi-level structure of LIGGGHTS(R)-PUBLIC and its class
organization, but functions (class methods) that do actual
computations are written in vanilla C-style code and operate on simple
C-style data structures (vectors and arrays).</p>
<p>Most of the new features described in this section require you to
write a new C++ derived class (except for exceptions described below,
where you can make small edits to existing files).  Creating a new
class requires 2 files, a source code file (<em>.cpp) and a header file
(</em>.h).  The derived class must provide certain methods to work as a
new option.  Depending on how different your new feature is compared
to existing features, you can either derive from the base class
itself, or from a derived class that already exists.  Enabling LIGGGHTS(R)-PUBLIC
to invoke the new class is as simple as putting the two source
files in the src dir and re-building LIGGGHTS(R)-PUBLIC.</p>
<p>The advantage of C++ and its object-orientation is that all the code
and variables needed to define the new feature are in the 2 files you
write, and thus shouldn&#8217;t make the rest of LIGGGHTS(R)-PUBLIC more complex or
cause side-effect bugs.</p>
<p>Here is a concrete example.  Suppose you write 2 files pair_foo.cpp
and pair_foo.h that define a new class PairFoo that computes pairwise
potentials described in the classic 1997 <a class="reference internal" href="#foo"><span>paper</span></a> by Foo, et al.
If you wish to invoke those potentials in a LIGGGHTS(R)-PUBLIC input script with a
command like</p>
<div class="highlight-python"><div class="highlight"><pre>pair_style foo 0.1 3.5
</pre></div>
</div>
<p>then your pair_foo.h file should be structured as follows:</p>
<div class="highlight-python"><div class="highlight"><pre>#ifdef PAIR_CLASS
PairStyle(foo,PairFoo)
#else
...
(class definition for PairFoo)
...
#endif
</pre></div>
</div>
<p>where &#8220;foo&#8221; is the style keyword in the pair_style command, and
PairFoo is the class name defined in your pair_foo.cpp and pair_foo.h
files.</p>
<p>When you re-build LIGGGHTS(R)-PUBLIC, your new pairwise potential becomes part of
the executable and can be invoked with a pair_style command like the
example above.  Arguments like 0.1 and 3.5 can be defined and
processed by your new class.</p>
<p>As illustrated by this pairwise example, many kinds of options are
referred to in the LIGGGHTS(R)-PUBLIC documentation as the &#8220;style&#8221; of a particular
command.</p>
<p>The instructions below give the header file for the base class that
these styles are derived from.  Public variables in that file are ones
used and set by the derived classes which are also used by the base
class.  Sometimes they are also used by the rest of LIGGGHTS(R)-PUBLIC.  Virtual
functions in the base class header file which are set = 0 are ones you
must define in your new derived class to give it the functionality
LIGGGHTS(R)-PUBLIC expects.  Virtual functions that are not set to 0 are functions
you can optionally define.</p>
<p>Additionally, new output options can be added directly to the
thermo.cpp, dump_custom.cpp, and variable.cpp files as explained
below.</p>
<p>Here are additional guidelines for modifying LIGGGHTS(R)-PUBLIC and adding new
functionality:</p>
<ul class="simple">
<li>Think about whether what you want to do would be better as a pre- or
post-processing step.  Many computations are more easily and more
quickly done that way.</li>
<li>Don&#8217;t do anything within the timestepping of a run that isn&#8217;t
parallel.  E.g. don&#8217;t accumulate a bunch of data on a single processor
and analyze it.  You run the risk of seriously degrading the parallel
efficiency.</li>
<li>If your new feature reads arguments or writes output, make sure you
follow the unit conventions discussed by the <a class="reference internal" href="units.html"><em>units</em></a>
command.</li>
<li>If you add something you think is truly useful and doesn&#8217;t impact
LIGGGHTS(R)-PUBLIC performance when it isn&#8217;t used, send an email to the
<a class="reference external" href="http://lammps.sandia.gov/authors.html">developers</a>.  We might be
interested in adding it to the LIGGGHTS(R)-PUBLIC distribution.  See further
details on this at the bottom of this page.</li>
</ul>
<div class="section" id="atom-styles">
<span id="mod-1"></span><h2><a class="toc-backref" href="#id9">9.1. Atom styles</a><a class="headerlink" href="#atom-styles" title="Permalink to this headline">¶</a></h2>
<p>Classes that define an <a class="reference internal" href="atom_style.html"><em>atom style</em></a> are derived from
the AtomVec class and managed by the Atom class.  The atom style
determines what attributes are associated with an atom.  A new atom
style can be created if one of the existing atom styles does not
define all the attributes you need to store and communicate with
atoms.</p>
<p>Atom_vec_atomic.cpp is a simple example of an atom style.</p>
<p>Here is a brief description of methods you define in your new derived
class.  See atom_vec.h for details.</p>
<table border="1" class="docutils">
<colgroup>
<col width="22%" />
<col width="78%" />
</colgroup>
<tbody valign="top">
<tr class="row-odd"><td>init</td>
<td>one time setup (optional)</td>
</tr>
<tr class="row-even"><td>grow</td>
<td>re-allocate atom arrays to longer lengths (required)</td>
</tr>
<tr class="row-odd"><td>grow_reset</td>
<td>make array pointers in Atom and AtomVec classes consistent (required)</td>
</tr>
<tr class="row-even"><td>copy</td>
<td>copy info for one atom to another atom&#8217;s array locations (required)</td>
</tr>
<tr class="row-odd"><td>pack_comm</td>
<td>store an atom&#8217;s info in a buffer communicated every timestep (required)</td>
</tr>
<tr class="row-even"><td>pack_comm_vel</td>
<td>add velocity info to communication buffer (required)</td>
</tr>
<tr class="row-odd"><td>pack_comm_hybrid</td>
<td>store extra info unique to this atom style (optional)</td>
</tr>
<tr class="row-even"><td>unpack_comm</td>
<td>retrieve an atom&#8217;s info from the buffer (required)</td>
</tr>
<tr class="row-odd"><td>unpack_comm_vel</td>
<td>also retrieve velocity info (required)</td>
</tr>
<tr class="row-even"><td>unpack_comm_hybrid</td>
<td>retreive extra info unique to this atom style (optional)</td>
</tr>
<tr class="row-odd"><td>pack_reverse</td>
<td>store an atom&#8217;s info in a buffer communicating partial forces  (required)</td>
</tr>
<tr class="row-even"><td>pack_reverse_hybrid</td>
<td>store extra info unique to this atom style (optional)</td>
</tr>
<tr class="row-odd"><td>unpack_reverse</td>
<td>retrieve an atom&#8217;s info from the buffer (required)</td>
</tr>
<tr class="row-even"><td>unpack_reverse_hybrid</td>
<td>retreive extra info unique to this atom style (optional)</td>
</tr>
<tr class="row-odd"><td>pack_border</td>
<td>store an atom&#8217;s info in a buffer communicated on neighbor re-builds (required)</td>
</tr>
<tr class="row-even"><td>pack_border_vel</td>
<td>add velocity info to buffer (required)</td>
</tr>
<tr class="row-odd"><td>pack_border_hybrid</td>
<td>store extra info unique to this atom style (optional)</td>
</tr>
<tr class="row-even"><td>unpack_border</td>
<td>retrieve an atom&#8217;s info from the buffer (required)</td>
</tr>
<tr class="row-odd"><td>unpack_border_vel</td>
<td>also retrieve velocity info (required)</td>
</tr>
<tr class="row-even"><td>unpack_border_hybrid</td>
<td>retreive extra info unique to this atom style (optional)</td>
</tr>
<tr class="row-odd"><td>pack_exchange</td>
<td>store all an atom&#8217;s info to migrate to another processor (required)</td>
</tr>
<tr class="row-even"><td>unpack_exchange</td>
<td>retrieve an atom&#8217;s info from the buffer (required)</td>
</tr>
<tr class="row-odd"><td>size_restart</td>
<td>number of restart quantities associated with proc&#8217;s atoms (required)</td>
</tr>
<tr class="row-even"><td>pack_restart</td>
<td>pack atom quantities into a buffer (required)</td>
</tr>
<tr class="row-odd"><td>unpack_restart</td>
<td>unpack atom quantities from a buffer (required)</td>
</tr>
<tr class="row-even"><td>create_atom</td>
<td>create an individual atom of this style (required)</td>
</tr>
<tr class="row-odd"><td>data_atom</td>
<td>parse an atom line from the data file (required)</td>
</tr>
<tr class="row-even"><td>data_atom_hybrid</td>
<td>parse additional atom info unique to this atom style (optional)</td>
</tr>
<tr class="row-odd"><td>data_vel</td>
<td>parse one line of velocity information from data file (optional)</td>
</tr>
<tr class="row-even"><td>data_vel_hybrid</td>
<td>parse additional velocity data unique to this atom style (optional)</td>
</tr>
<tr class="row-odd"><td>memory_usage</td>
<td>tally memory allocated by atom arrays (required)</td>
</tr>
</tbody>
</table>
<p>The constructor of the derived class sets values for several variables
that you must set when defining a new atom style, which are documented
in atom_vec.h.  New atom arrays are defined in atom.cpp.  Search for
the word &#8220;customize&#8221; and you will find locations you will need to
modify.</p>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">It is possible to add some attributes, such as a
molecule ID, to atom styles that do not have them via the <code class="xref doc docutils literal"><span class="pre">fix</span> <span class="pre">property/atom</span></code> command.  This command also
allows new custom attributes consisting of extra integer or
floating-point values to be added to atoms.  See the <code class="xref doc docutils literal"><span class="pre">fix</span> <span class="pre">property/atom</span></code> doc page for examples of cases
where this is useful and details on how to initialize, access, and
output the custom values.</p>
</div>
<p>New <a class="reference internal" href="pair_style.html"><em>pair styles</em></a>, <a class="reference internal" href="fix.html"><em>fixes</em></a>, or
<a class="reference internal" href="compute.html"><em>computes</em></a> can be added to LIGGGHTS(R)-PUBLIC, as discussed below.
The code for these classes can use the per-atom properties defined by
fix property/atom.  The Atom class has a find_custom() method that is
useful in this context:</p>
<div class="highlight-python"><div class="highlight"><pre>int index = atom-&gt;find_custom(char *name, int &amp;flag);
</pre></div>
</div>
<p>The &#8220;name&#8221; of a custom attribute, as specified in the <code class="xref doc docutils literal"><span class="pre">fix</span> <span class="pre">property/atom</span></code> command, is checked to verify
that it exists and its index is returned.  The method also sets flag =
0/1 depending on whether it is an integer or floating-point attribute.
The vector of values associated with the attribute can then be
accessed using the returned index as</p>
<div class="highlight-python"><div class="highlight"><pre>int *ivector = atom-&gt;ivector[index];
double *dvector = atom-&gt;dvector[index];
</pre></div>
</div>
<p>Ivector or dvector are vectors of length Nlocal = # of owned atoms,
which store the attributes of individual atoms.</p>
<hr class="docutils" />
</div>
<div class="section" id="compute-styles">
<span id="mod-2"></span><h2><a class="toc-backref" href="#id10">9.2. Compute styles</a><a class="headerlink" href="#compute-styles" title="Permalink to this headline">¶</a></h2>
<p>Classes that compute scalar and vector quantities like temperature
and the pressure tensor, as well as classes that compute per-atom
quantities like kinetic energy and the centro-symmetry parameter
are derived from the Compute class.  New styles can be created
to add new calculations to LIGGGHTS(R)-PUBLIC.</p>
<p>Compute_temp.cpp is a simple example of computing a scalar
temperature.  Compute_ke_atom.cpp is a simple example of computing
per-atom kinetic energy.</p>
<p>Here is a brief description of methods you define in your new derived
class.  See compute.h for details.</p>
<table border="1" class="docutils">
<colgroup>
<col width="22%" />
<col width="78%" />
</colgroup>
<tbody valign="top">
<tr class="row-odd"><td>init</td>
<td>perform one time setup (required)</td>
</tr>
<tr class="row-even"><td>init_list</td>
<td>neighbor list setup, if needed (optional)</td>
</tr>
<tr class="row-odd"><td>compute_scalar</td>
<td>compute a scalar quantity (optional)</td>
</tr>
<tr class="row-even"><td>compute_vector</td>
<td>compute a vector of quantities (optional)</td>
</tr>
<tr class="row-odd"><td>compute_peratom</td>
<td>compute one or more quantities per atom (optional)</td>
</tr>
<tr class="row-even"><td>compute_local</td>
<td>compute one or more quantities per processor (optional)</td>
</tr>
<tr class="row-odd"><td>pack_comm</td>
<td>pack a buffer with items to communicate (optional)</td>
</tr>
<tr class="row-even"><td>unpack_comm</td>
<td>unpack the buffer (optional)</td>
</tr>
<tr class="row-odd"><td>pack_reverse</td>
<td>pack a buffer with items to reverse communicate (optional)</td>
</tr>
<tr class="row-even"><td>unpack_reverse</td>
<td>unpack the buffer (optional)</td>
</tr>
<tr class="row-odd"><td>remove_bias</td>
<td>remove velocity bias from one atom (optional)</td>
</tr>
<tr class="row-even"><td>remove_bias_all</td>
<td>remove velocity bias from all atoms in group (optional)</td>
</tr>
<tr class="row-odd"><td>restore_bias</td>
<td>restore velocity bias for one atom after remove_bias (optional)</td>
</tr>
<tr class="row-even"><td>restore_bias_all</td>
<td>same as before, but for all atoms in group (optional)</td>
</tr>
<tr class="row-odd"><td>memory_usage</td>
<td>tally memory usage (optional)</td>
</tr>
</tbody>
</table>
<hr class="docutils" />
</div>
<div class="section" id="dump-styles">
<span id="mod-3"></span><h2><a class="toc-backref" href="#id11">9.3. Dump styles</a><a class="headerlink" href="#dump-styles" title="Permalink to this headline">¶</a></h2>
</div>
<div class="section" id="dump-custom-output-options">
<span id="mod-4"></span><h2><a class="toc-backref" href="#id12">9.4. Dump custom output options</a><a class="headerlink" href="#dump-custom-output-options" title="Permalink to this headline">¶</a></h2>
<p>Classes that dump per-atom info to files are derived from the Dump
class.  To dump new quantities or in a new format, a new derived dump
class can be added, but it is typically simpler to modify the
DumpCustom class contained in the dump_custom.cpp file.</p>
<p>Dump_atom.cpp is a simple example of a derived dump class.</p>
<p>Here is a brief description of methods you define in your new derived
class.  See dump.h for details.</p>
<table border="1" class="docutils">
<colgroup>
<col width="22%" />
<col width="78%" />
</colgroup>
<tbody valign="top">
<tr class="row-odd"><td>write_header</td>
<td>write the header section of a snapshot of atoms</td>
</tr>
<tr class="row-even"><td>count</td>
<td>count the number of lines a processor will output</td>
</tr>
<tr class="row-odd"><td>pack</td>
<td>pack a proc&#8217;s output data into a buffer</td>
</tr>
<tr class="row-even"><td>write_data</td>
<td>write a proc&#8217;s data to a file</td>
</tr>
</tbody>
</table>
<p>See the <a class="reference internal" href="dump.html"><em>dump</em></a> command and its <em>custom</em> style for a list of
keywords for atom information that can already be dumped by
DumpCustom.  It includes options to dump per-atom info from Compute
classes, so adding a new derived Compute class is one way to calculate
new quantities to dump.</p>
<p>Alternatively, you can add new keywords to the dump custom command.
Search for the word &#8220;customize&#8221; in dump_custom.cpp to see the
half-dozen or so locations where code will need to be added.</p>
<hr class="docutils" />
</div>
<div class="section" id="fix-styles">
<span id="mod-5"></span><h2><a class="toc-backref" href="#id13">9.5. Fix styles</a><a class="headerlink" href="#fix-styles" title="Permalink to this headline">¶</a></h2>
<p>In LIGGGHTS(R)-PUBLIC, a &#8220;fix&#8221; is any operation that is computed during
timestepping that alters some property of the system.  Essentially
everything that happens during a simulation besides force computation,
neighbor list construction, and output, is a &#8220;fix&#8221;.  This includes
time integration (update of coordinates and velocities), force
constraints or boundary conditions (SHAKE or walls), and diagnostics
(compute a diffusion coefficient).  New styles can be created to add
new options to LIGGGHTS(R)-PUBLIC.</p>
<p>Fix_setforce.cpp is a simple example of setting forces on atoms to
prescribed values.  There are dozens of fix options already in LIGGGHTS(R)-PUBLIC;
choose one as a template that is similar to what you want to
implement.</p>
<p>Here is a brief description of methods you can define in your new
derived class.  See fix.h for details.</p>
<table border="1" class="docutils">
<colgroup>
<col width="22%" />
<col width="78%" />
</colgroup>
<tbody valign="top">
<tr class="row-odd"><td>setmask</td>
<td>determines when the fix is called during the timestep (required)</td>
</tr>
<tr class="row-even"><td>init</td>
<td>initialization before a run (optional)</td>
</tr>
<tr class="row-odd"><td>setup_pre_exchange</td>
<td>called before atom exchange in setup (optional)</td>
</tr>
<tr class="row-even"><td>setup_pre_force</td>
<td>called before force computation in setup (optional)</td>
</tr>
<tr class="row-odd"><td>setup</td>
<td>called immediately before the 1st timestep and after forces are computed (optional)</td>
</tr>
<tr class="row-even"><td>min_setup_pre_force</td>
<td>like setup_pre_force, but for minimizations instead of MD runs (optional)</td>
</tr>
<tr class="row-odd"><td>min_setup</td>
<td>like setup, but for minimizations instead of MD runs (optional)</td>
</tr>
<tr class="row-even"><td>initial_integrate</td>
<td>called at very beginning of each timestep (optional)</td>
</tr>
<tr class="row-odd"><td>pre_exchange</td>
<td>called before atom exchange on re-neighboring steps (optional)</td>
</tr>
<tr class="row-even"><td>pre_neighbor</td>
<td>called before neighbor list build (optional)</td>
</tr>
<tr class="row-odd"><td>pre_force</td>
<td>called after pair &amp; molecular forces are computed (optional)</td>
</tr>
<tr class="row-even"><td>post_force</td>
<td>called after pair &amp; molecular forces are computed and communicated (optional)</td>
</tr>
<tr class="row-odd"><td>final_integrate</td>
<td>called at end of each timestep (optional)</td>
</tr>
<tr class="row-even"><td>end_of_step</td>
<td>called at very end of timestep (optional)</td>
</tr>
<tr class="row-odd"><td>write_restart</td>
<td>dumps fix info to restart file (optional)</td>
</tr>
<tr class="row-even"><td>restart</td>
<td>uses info from restart file to re-initialize the fix (optional)</td>
</tr>
<tr class="row-odd"><td>grow_arrays</td>
<td>allocate memory for atom-based arrays used by fix (optional)</td>
</tr>
<tr class="row-even"><td>copy_arrays</td>
<td>copy atom info when an atom migrates to a new processor (optional)</td>
</tr>
<tr class="row-odd"><td>pack_exchange</td>
<td>store atom&#8217;s data in a buffer (optional)</td>
</tr>
<tr class="row-even"><td>unpack_exchange</td>
<td>retrieve atom&#8217;s data from a buffer (optional)</td>
</tr>
<tr class="row-odd"><td>pack_restart</td>
<td>store atom&#8217;s data for writing to restart file (optional)</td>
</tr>
<tr class="row-even"><td>unpack_restart</td>
<td>retrieve atom&#8217;s data from a restart file buffer (optional)</td>
</tr>
<tr class="row-odd"><td>size_restart</td>
<td>size of atom&#8217;s data (optional)</td>
</tr>
<tr class="row-even"><td>maxsize_restart</td>
<td>max size of atom&#8217;s data (optional)</td>
</tr>
<tr class="row-odd"><td>setup_pre_force_respa</td>
<td>same as setup_pre_force, but for rRESPA (optional)</td>
</tr>
<tr class="row-even"><td>initial_integrate_respa</td>
<td>same as initial_integrate, but for rRESPA (optional)</td>
</tr>
<tr class="row-odd"><td>post_integrate_respa</td>
<td>called after the first half integration step is done in rRESPA (optional)</td>
</tr>
<tr class="row-even"><td>pre_force_respa</td>
<td>same as pre_force, but for rRESPA (optional)</td>
</tr>
<tr class="row-odd"><td>post_force_respa</td>
<td>same as post_force, but for rRESPA (optional)</td>
</tr>
<tr class="row-even"><td>final_integrate_respa</td>
<td>same as final_integrate, but for rRESPA (optional)</td>
</tr>
<tr class="row-odd"><td>min_pre_force</td>
<td>called after pair &amp; molecular forces are computed in minimizer (optional)</td>
</tr>
<tr class="row-even"><td>min_post_force</td>
<td>called after pair &amp; molecular forces are computed and communicated in minmizer (optional)</td>
</tr>
<tr class="row-odd"><td>min_store</td>
<td>store extra data for linesearch based minimization on a LIFO stack (optional)</td>
</tr>
<tr class="row-even"><td>min_pushstore</td>
<td>push the minimization LIFO stack one element down (optional)</td>
</tr>
<tr class="row-odd"><td>min_popstore</td>
<td>pop the minimization LIFO stack one element up (optional)</td>
</tr>
<tr class="row-even"><td>min_clearstore</td>
<td>clear minimization LIFO stack (optional)</td>
</tr>
<tr class="row-odd"><td>min_step</td>
<td>reset or move forward on line search minimization (optional)</td>
</tr>
<tr class="row-even"><td>min_dof</td>
<td>report number of degrees of freedom <em>added</em> by this fix in minimization (optional)</td>
</tr>
<tr class="row-odd"><td>max_alpha</td>
<td>report maximum allowed step size during linesearch minimization (optional)</td>
</tr>
<tr class="row-even"><td>pack_comm</td>
<td>pack a buffer to communicate a per-atom quantity (optional)</td>
</tr>
<tr class="row-odd"><td>unpack_comm</td>
<td>unpack a buffer to communicate a per-atom quantity (optional)</td>
</tr>
<tr class="row-even"><td>pack_reverse_comm</td>
<td>pack a buffer to reverse communicate a per-atom quantity (optional)</td>
</tr>
<tr class="row-odd"><td>unpack_reverse_comm</td>
<td>unpack a buffer to reverse communicate a per-atom quantity (optional)</td>
</tr>
<tr class="row-even"><td>dof</td>
<td>report number of degrees of freedom <em>removed</em> by this fix during MD (optional)</td>
</tr>
<tr class="row-odd"><td>compute_scalar</td>
<td>return a global scalar property that the fix computes (optional)</td>
</tr>
<tr class="row-even"><td>compute_vector</td>
<td>return a component of a vector property that the fix computes (optional)</td>
</tr>
<tr class="row-odd"><td>compute_array</td>
<td>return a component of an array property that the fix computes (optional)</td>
</tr>
<tr class="row-even"><td>deform</td>
<td>called when the box size is changed (optional)</td>
</tr>
<tr class="row-odd"><td>reset_target</td>
<td>called when a change of the target temperature is requested during a run (optional)</td>
</tr>
<tr class="row-even"><td>reset_dt</td>
<td>is called when a change of the time step is requested during a run (optional)</td>
</tr>
<tr class="row-odd"><td>modify_param</td>
<td>called when a fix_modify request is executed (optional)</td>
</tr>
<tr class="row-even"><td>memory_usage</td>
<td>report memory used by fix (optional)</td>
</tr>
<tr class="row-odd"><td>thermo</td>
<td>compute quantities for thermodynamic output (optional)</td>
</tr>
</tbody>
</table>
<p>Typically, only a small fraction of these methods are defined for a
particular fix.  Setmask is mandatory, as it determines when the fix
will be invoked during the timestep.  Fixes that perform time
integration (<em>nve</em>, <em>nvt</em>, <em>npt</em>) implement initial_integrate() and
final_integrate() to perform velocity Verlet updates.  Fixes that
constrain forces implement post_force().</p>
<p>Fixes that perform diagnostics typically implement end_of_step().  For
an end_of_step fix, one of your fix arguments must be the variable
&#8220;nevery&#8221; which is used to determine when to call the fix and you must
set this variable in the constructor of your fix.  By convention, this
is the first argument the fix defines (after the ID, group-ID, style).</p>
<p>If the fix needs to store information for each atom that persists from
timestep to timestep, it can manage that memory and migrate the info
with the atoms as they move from processors to processor by
implementing the grow_arrays, copy_arrays, pack_exchange, and
unpack_exchange methods.  Similarly, the pack_restart and
unpack_restart methods can be implemented to store information about
the fix in restart files.  If you wish an integrator or force
constraint fix to work with rRESPA (see the <a class="reference internal" href="run_style.html"><em>run_style</em></a>
command), the initial_integrate, post_force_integrate, and
final_integrate_respa methods can be implemented.  The thermo method
enables a fix to contribute values to thermodynamic output, as printed
quantities and/or to be summed to the potential energy of the system.</p>
<hr class="docutils" />
</div>
<div class="section" id="input-script-commands">
<span id="mod-6"></span><h2><a class="toc-backref" href="#id14">9.6. Input script commands</a><a class="headerlink" href="#input-script-commands" title="Permalink to this headline">¶</a></h2>
<p>New commands can be added to LIGGGHTS(R)-PUBLIC input scripts by adding new
classes that have a &#8220;command&#8221; method.  For example, the create_atoms,
read_data, velocity, and run commands are all implemented in this
fashion.  When such a command is encountered in the LIGGGHTS(R)-PUBLIC input
script, LIGGGHTS(R)-PUBLIC simply creates a class with the corresponding name,
invokes the &#8220;command&#8221; method of the class, and passes it the arguments
from the input script.  The command method can perform whatever
operations it wishes on LIGGGHTS(R)-PUBLIC data structures.</p>
<p>The single method your new class must define is as follows:</p>
<table border="1" class="docutils">
<colgroup>
<col width="18%" />
<col width="82%" />
</colgroup>
<tbody valign="top">
<tr class="row-odd"><td>command</td>
<td>operations performed by the new command</td>
</tr>
</tbody>
</table>
<p>Of course, the new class can define other methods and variables as
needed.</p>
<hr class="docutils" />
</div>
<div class="section" id="pairwise-potentials">
<span id="mod-7"></span><h2><a class="toc-backref" href="#id15">9.7. Pairwise potentials</a><a class="headerlink" href="#pairwise-potentials" title="Permalink to this headline">¶</a></h2>
<p>Classes that compute pairwise interactions are derived from the Pair
class.  In LIGGGHTS(R)-PUBLIC, pairwise calculation include manybody potentials
such as EAM or Tersoff where particles interact without a static bond
topology.  New styles can be created to add new pair potentials to
LIGGGHTS(R)-PUBLIC.</p>
<p>Here is a brief description of the class methods in pair.h:</p>
<table border="1" class="docutils">
<colgroup>
<col width="32%" />
<col width="68%" />
</colgroup>
<tbody valign="top">
<tr class="row-odd"><td>compute</td>
<td>workhorse routine that computes pairwise interactions</td>
</tr>
<tr class="row-even"><td>settings</td>
<td>reads the input script line with arguments you define</td>
</tr>
<tr class="row-odd"><td>coeff</td>
<td>set coefficients for one i,j type pair</td>
</tr>
<tr class="row-even"><td>init_one</td>
<td>perform initialization for one i,j type pair</td>
</tr>
<tr class="row-odd"><td>init_style</td>
<td>initialization specific to this pair style</td>
</tr>
<tr class="row-even"><td>write &amp; read_restart</td>
<td>write/read i,j pair coeffs to restart files</td>
</tr>
<tr class="row-odd"><td>write &amp; read_restart_settings</td>
<td>write/read global settings to restart files</td>
</tr>
<tr class="row-even"><td>single</td>
<td>force and energy of a single pairwise interaction between 2 atoms</td>
</tr>
<tr class="row-odd"><td>compute_inner/middle/outer</td>
<td>versions of compute used by rRESPA</td>
</tr>
</tbody>
</table>
<p>The inner/middle/outer routines are optional.</p>
<hr class="docutils" />
</div>
<div class="section" id="region-styles">
<span id="mod-8"></span><h2><a class="toc-backref" href="#id16">9.8. Region styles</a><a class="headerlink" href="#region-styles" title="Permalink to this headline">¶</a></h2>
<p>Classes that define geometric regions are derived from the Region
class.  Regions are used elsewhere in LIGGGHTS(R)-PUBLIC to group atoms, delete
atoms to create a void, insert atoms in a specified region, etc.  New
styles can be created to add new region shapes to LIGGGHTS(R)-PUBLIC.</p>
<p>Region_sphere.cpp is an example of a spherical region.</p>
<p>Here is a brief description of methods you define in your new derived
class.  See region.h for details.</p>
<table border="1" class="docutils">
<colgroup>
<col width="14%" />
<col width="86%" />
</colgroup>
<tbody valign="top">
<tr class="row-odd"><td>match</td>
<td>determine whether a point is in the region</td>
</tr>
</tbody>
</table>
<hr class="docutils" />
</div>
<div class="section" id="thermodynamic-output-options">
<span id="mod-9"></span><h2><a class="toc-backref" href="#id17">9.9. Thermodynamic output options</a><a class="headerlink" href="#thermodynamic-output-options" title="Permalink to this headline">¶</a></h2>
<p>There is one class that computes and prints thermodynamic information
to the screen and log file; see the file thermo.cpp.</p>
<p>There are two styles defined in thermo.cpp: &#8220;one&#8221; and &#8220;multi&#8221;.  There
is also a flexible &#8220;custom&#8221; style which allows the user to explicitly
list keywords for quantities to print when thermodynamic info is
output.  See the <a class="reference internal" href="thermo_style.html"><em>thermo_style</em></a> command for a list
of defined quantities.</p>
<p>The thermo styles (one, multi, etc) are simply lists of keywords.
Adding a new style thus only requires defining a new list of keywords.
Search for the word &#8220;customize&#8221; with references to &#8220;thermo style&#8221; in
thermo.cpp to see the two locations where code will need to be added.</p>
<p>New keywords can also be added to thermo.cpp to compute new quantities
for output.  Search for the word &#8220;customize&#8221; with references to
&#8220;keyword&#8221; in thermo.cpp to see the several locations where code will
need to be added.</p>
<p>Note that the <a class="reference internal" href="thermo.html"><em>thermo_style custom</em></a> command already allows
for thermo output of quantities calculated by <a class="reference internal" href="fix.html"><em>fixes</em></a>,
<a class="reference internal" href="compute.html"><em>computes</em></a>, and <a class="reference internal" href="variable.html"><em>variables</em></a>.  Thus, it may
be simpler to compute what you wish via one of those constructs, than
by adding a new keyword to the thermo command.</p>
<hr class="docutils" />
</div>
<div class="section" id="variable-options">
<span id="mod-10"></span><h2><a class="toc-backref" href="#id18">9.10. Variable options</a><a class="headerlink" href="#variable-options" title="Permalink to this headline">¶</a></h2>
<p>There is one class that computes and stores <a class="reference internal" href="variable.html"><em>variable</em></a>
information in LIGGGHTS(R)-PUBLIC; see the file variable.cpp.  The value
associated with a variable can be periodically printed to the screen
via the <a class="reference internal" href="print.html"><em>print</em></a>, <a class="reference internal" href="fix_print.html"><em>fix print</em></a>, or
<a class="reference internal" href="thermo_style.html"><em>thermo_style custom</em></a> commands.  Variables of style
&#8220;equal&#8221; can compute complex equations that involve the following types
of arguments:</p>
<p>thermo keywords = ke, vol, atoms, ...
other variables = v_a, v_myvar, ...
math functions = div(x,y), mult(x,y), add(x,y), ...
group functions = mass(group), xcm(group,x), ...
atom values = x**123**, y**3**, vx**34**, ...
compute values = c_mytemp**0**, c_thermo_press**3**, ...</p>
<p>Adding keywords for the <a class="reference internal" href="thermo_style.html"><em>thermo_style custom</em></a> command
(which can then be accessed by variables) was discussed
<a class="reference internal" href="Section_howto.html#thermo"><span>here</span></a> on this page.</p>
<p>Adding a new math function of one or two arguments can be done by
editing one section of the Variable::evaulate() method.  Search for
the word &#8220;customize&#8221; to find the appropriate location.</p>
<p>Adding a new group function can be done by editing one section of the
Variable::evaulate() method.  Search for the word &#8220;customize&#8221; to find
the appropriate location.  You may need to add a new method to the
Group class as well (see the group.cpp file).</p>
<p>Accessing a new atom-based vector can be done by editing one section
of the Variable::evaulate() method.  Search for the word &#8220;customize&#8221;
to find the appropriate location.</p>
<p>Adding new <a class="reference internal" href="compute.html"><em>compute styles</em></a> (whose calculated values can
then be accessed by variables) was discussed
<a class="reference internal" href="Section_howto.html#compute"><span>here</span></a> on this page.</p>
</div>
<div class="section" id="submitting-new-features-for-inclusion-in-liggghts-r-public">
<span id="mod-11"></span><h2><a class="toc-backref" href="#id19">9.11. Submitting new features for inclusion in LIGGGHTS(R)-PUBLIC</a><a class="headerlink" href="#submitting-new-features-for-inclusion-in-liggghts-r-public" title="Permalink to this headline">¶</a></h2>
<p>We encourage users to submit new features that they add to LIGGGHTS(R)-PUBLIC, especially if
you think the features will be of interest to other users.  If they
are broadly useful we may add them as core files to LIGGGHTS(R)-PUBLIC.</p>
<p>The previous sections of this doc page describe how to add new
features of various kinds to LIGGGHTS(R)-PUBLIC.  Packages are simply collections
of one or more new class files which are invoked as a new &#8220;style&#8221;
within a LIGGGHTS(R)-PUBLIC input script.  If designed correctly, these additions
typically do not require changes to the main core of LIGGGHTS(R)-PUBLIC; they are
simply add-on files.</p>
<p>Here is what you need to do to submit a user package or single file
for our consideration.  Following these steps will save time for both
you and us.  See existing package files for examples.</p>
<ul class="simple">
<li>All source files you provide must compile with the most current
version of LIGGGHTS(R)-PUBLIC.</li>
<li>If you want your file(s) to be added to main LIGGGHTS(R)-PUBLIC or one of its
standard packages, then it needs to be written in a style compatible
with other LIGGGHTS(R)-PUBLIC source files.  This is so the developers can
understand it and hopefully maintain it.  This basically means that
the code accesses data structures, performs its operations, and is
formatted similar to other LIGGGHTS(R)-PUBLIC source files, including the use of
the error class for error and warning messages.</li>
<li>Your new source files need to have the LIGGGHTS(R)-PUBLIC copyright, GPL notice,
and your name at the top, like other LIGGGHTS(R)-PUBLIC source files.  They need
to create a class that is inside the LIGGGHTS(R)-PUBLIC namespace.  I.e. they do not need to be
in the same stylistic format and syntax as other LIGGGHTS(R)-PUBLIC files, though
that would be nice.</li>
<li>Finally, you must also send a documentation file for each new command
or style you are adding to LIGGGHTS(R)-PUBLIC.  This will be one file for a
single-file feature.  For a package, it might be several files.  These
are simple text files which we will convert to HTML.  They must be in
the same format as other <a href="#id7"><span class="problematic" id="id8">*</span></a>.txt files in the lammps/doc directory for
similar commands and styles.  The txt2html
tool we use to do the conversion can be downloaded from <a class="reference external" href="http://www.sandia.gov/~sjplimp/download.html">this site</a>, so you can perform
the HTML conversion yourself to proofread your doc page.</li>
</ul>
<p>Note that the more clear and self-explanatory you make your doc and
README files, the more likely it is that users will try out your new
feature.</p>
<p id="foo"><strong>(Foo)</strong> Foo, Morefoo, and Maxfoo, J of Classic Potentials, 75, 345 (1997).</p>
</div>
</div>


           </div>
           <div class="articleComments">
            
           </div>
          </div>
          <footer>
  
    <div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
      
        <a href="Section_python.html" class="btn btn-neutral float-right" title="10. Python interface to LIGGGHTS(R)-PUBLIC" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right"></span></a>
      
      
        <a href="Section_howto.html" class="btn btn-neutral" title="8. How-to discussions" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left"></span> Previous</a>
      
    </div>
  

  <hr/>

  <div role="contentinfo">
    <p>
        &copy; Copyright 2016, DCS Computing GmbH, JKU Linz and Sandia Corporation.

    </p>
  </div>
  Built with <a href="http://sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/snide/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>. 

</footer>

        </div>
      </div>

    </section>

  </div>
  


  

    <script type="text/javascript">
        var DOCUMENTATION_OPTIONS = {
            URL_ROOT:'./',
            VERSION:'v3.X',
            LANGUAGE:'None',
            COLLAPSE_INDEX:false,
            FILE_SUFFIX:'.html',
            HAS_SOURCE:  true,
            SOURCELINK_SUFFIX: ''
        };
    </script>
      <script type="text/javascript" src="_static/jquery.js"></script>
      <script type="text/javascript" src="_static/underscore.js"></script>
      <script type="text/javascript" src="_static/doctools.js"></script>

  

  
  
    <script type="text/javascript" src="_static/js/theme.js"></script>
  

  
  
  <script type="text/javascript">
      jQuery(function () {
          SphinxRtdTheme.StickyNav.enable();
      });
  </script>
   

</body>
</html>